Skip to content

Conversation

encukou
Copy link
Member

@encukou encukou commented Aug 6, 2025

Continuing from #135942, this tackles the f-string section.

Much of the information was duplicated in stdtypes.rst; this PR keeps lexical/syntactical details in Lexical Analysis and the evaluation & runtime behaviour in Standard types, with cross-references between the two.
Since the t-string section only listed differences from f-strings, and the grammar for the two is equivalent, that section was moved to Standard types almost entirely.


📚 Documentation preview 📚: https://cpython-previews--137469.org.readthedocs.build/

Copy link
Member

@AA-Turner AA-Turner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry for taking a while to review this. I started adding lots of detailed comments, but have abandoned that for now, because my overall feeedback took shape at a higher level -- I don't think lexical analysis is the right place for large parts of this content. For example, explaning the detail of how replacement fields work necessarily references expressions, which we haven't yet covered in the PLR, as we're still notionally in the tokenising/lexing phase.

From the introduction of the chapter, 'This chapter describes how the lexical analyzer breaks a file into tokens.', and I think we make a mistake by trying to cover/explain all of f-strings here.

I wonder if there is a clear enough distinction we can draw between the lexing of f-strings (that could go into lexical_analysis, the parsing & grammar thereof (that could go into e.g. expressions(?)), and the runtime evaluation of the AST, e.g. how format specs are evaluated (that could go into stdtypes?)

I think there are bits of the treatment & grouping that are somewhat nebulous and could go either way, but I'd prefer to be stricter with the content in the Language Reference, even if that means splitting up the coverage of f-strings into a few places.

I'd be happy to work up a PR with something closer to my suggested split if it'd be useful, but otherwise let me know your thoughts.

A

@bedevere-app
Copy link

bedevere-app bot commented Oct 8, 2025

When you're done making the requested changes, leave the comment: I have made the requested changes; please review again.

And if you don't make the requested changes, you will be put in the comfy chair!

@encukou
Copy link
Member Author

encukou commented Oct 8, 2025

The question is: Does this PR bring the docs closer to the desired state? Would you be OK with basing your PR on this rather than the status quo?

I did try to move runtime stuff to stdtypes and lexical stuff to lexical_analysis, but yeah, this can always be improved.

@ericvsmith
Copy link
Member

This PR addresses #125496. I've closed that issue in preference to this one.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
awaiting changes docs Documentation in the Doc dir needs backport to 3.14 bugs and security fixes skip news
Projects
Status: Todo
Development

Successfully merging this pull request may close these issues.

Update the grammar for f-strings on "Lexical analysis" page f-string documentation not fully accurate
4 participants